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Disclaimer 
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Preface 


STARPAC,  the  Standards  Time  Series  and  Regression  Package,  is  a  library 
of  Fortran  subroutines  for  statistical  data  analysis  developed  by  the 
Statistical  Engineering  Division  (SED)  of  the  National  Bureau  of  Standards 
(NBS),  Boulder,  Colorado.  Earlier  versions  of  this  library  were  distributed 
by  the  SED  under  the  name  STATLIB  [Tryon  and  Donaldson,  1978] .  STARPAC 
incorporates  many  changes  to  STATLIB,  including  additional  statistical 
techniques,  improved  algorithms  and  enhanced  portability. 

We  are  releasing  STARPAC  source  code  in  segments  and  the  documentation  as 
a  series  of  NBS  Technical  Notes.  This  will  allow  us  to  make  the  new 
capabilities  of  STARPAC  available  more  quickly  and  to  facilitate  the  release 
of  future  changes.  This  Note  gives  an  overview  of  the  STARPAC  library, 
defines  conventions  used  in  the  documentation,  provides  an  example  using 
STARPAC  subroutines,  and  presents  general  background  material.  It  includes 
information  which  is  essential  for  using  the  STARPAC  library,  and  users  should 
be  familiar  with  its  contents  before  attempting  to  use  any  STARPAC 
subroutine. 

The  STARPAC  code  segments  consist  of  subroutines  for  nonlinear  least 
squares  regression,  time  series  analysis  (in  both  time  and  frequency  domains) , 
line  printer  graphics,  basic  statistical  analysis,  linear  least  squares 
regression,  and  nonlinear  optimization.  Users  may  obtain  a  list  of  the 
available  code  segments  and  their  associated  documentation  from  their  local 
installer  of  STARPAC,  or  directly  from  the  author. 

STARPAC  subroutines  feature: 

•  ease  of  use,  alone  and  with  other  Fortran  subroutine  libraries; 

•  extensive  error  handling  facilities; 

•  comprehensive  printed  reports; 

•  no  problem  size  restrictions  other  than  effective  machine  size;  and 

•  portability. 

Notation,  format,  and  naming  conventions  will  remain  constant  throughout 
the  series  of  Technical  Notes  documenting  STARPAC,  allowing  the  documentation 
for  each  code  segment  to  be  used  alone  or  in  conjunction  with  the 
documentation  for  another. 

The  code  for  STARPAC  was  developed  at  the  U.S.  Department  of  Commerce 
Boulder  Laboratories  on  a  CDC  CYBER  170/750  under  NOS  1.4,  and  all  examples 
presented  in  this  documentation  were  executed  in  this  environment  using  the 
FTN  4.8+552  compiler  with  rounding.  STARPAC  has  also  been  tested  on  the 
following  equipment. 


Computer  Facility 


IBM  4340  National  Center   for  Atmospheric  Research, 

VAX    11/780  Boulder,    Colorado 

Sperry    1100/82  National  Bureau   of   Standards, 

Gaithersburg,    Maryland 

Perkin-Elmer   3230  National  Bureau  of   Standards, 

Boulder,    Colorado 

Data  General  ECLIPSE   S/140  Forest  Fire  Laboratory, 

Riverside,    California 


STARPAC  is  written  in  Fortran  '66.  Adherence  to  a  portable  subset  of 
ANSI  Fortran  [1966]  has  been  verified  bv  the  PFORT  Verifier  [Ryder,  1974]. 
Workspace  and  machine-dependent  constants  are  supplied  using  subroutines  based 
on  the  Bell  Laboratories  "Framework  for  a  Portable  Library"  [Fox  et  al.  , 
1978a].  We  have  also  used  subroutines  from  LINPAQK  [Dongarra  et  al.  ,  1979], 
from  the  "Basic  Linear  Algebra  Subprograms  for  Fortran  Usage"  [Lawson  et  al.  , 
1979],  and  from  DATAPAC  [Filliben,  1977].  The  printed  report  generated  by  the 
statistical  analysis  subroutines  has  been  adapted  from  OMNITAR  II  [Hogben  et 
al.  ,    1971]  . 

Computer  facilities  for  the  STARPAC  project  have  been  provided  in  part  by 
the  NOAA  Computer  Services  Division,  Boulder,  Colorado,  and  we  gratefully 
acknowledge  their  support.  The  STARPAC  subroutine  library  is  the  result  of 
the  programming  efforts  of  Janet  R.  Donaldson  and  John  E.  Koontz,  with 
assistance  from  Ginger  A.  Caldwell,  Steven  M.  Keefer,  and  Linda  L.  Mitchell. 
Valuable  contributions  have  also  been  made  by  each  of  the  members  of  the 
Statistical  Engineering  Division  in  Boulder,  and  from  many  within  the  STARPAC 
user  community.  We  are  grateful  for  the  many  valuable  comments  that  we  have 
received  on  early  drafts  of  the  STARPAC  documentation;  we  wish  especially  to 
thank  Paul  T.  Boggs,  Ginger  A.  Caldwell,  Sally  E.  Howe,  John  E.  Koontz,  James 
T.  Ringland,  Ralph  M.  Slutz,  and  Dominic  F.  Vecchia.  Finally,  we  wish  to 
thank  Lorna  Buhse   for  excellent   manuscript   support. 


Janet  R.    Donaldson 

Peter  V.    Tryon    (deceased) 

September   1983 
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to 

STARPAC 

The  Standards  Time  Series  and  Regression  Package 

Janet  R.  Donaldson  and  Peter  V.  Tryon 

National  Bureau  of  Standards 
Washington,  DC  20234 

STARPAC,  the  Standards  Time  Series  and  Regression  Package,  is  a 
library  of  Fortran  subroutines  for  statistical  data  analysis 
developed  by  the  Statistical  Engineering  Division  (SED)  of  the 
National  Bureau  of  Standards  (NBS),  Boulder,  Colorado.  Earlier 
versions  of  this  library  were  distributed  by  the  SED  under  the  name 
STATLIB  [Tryon  and  Donaldson,  1978].  STARPAC  incorporates  many 
changes  to  STATLIB,  including  additional  statistical  techniques, 
improved  algorithms  and  enhanced  portability. 

STARPAC  emphasizes  the  statistical  interpretation  of  results, 
and,  for  this  reason,  comprehensive  printed  reports  of  auxiliary 
statistical  information,  often  in  graphical  form,  are  automatically 
provided  to  augment  the  basic  statistical  computations  performed  by 
each  user-callable  STARPAC  subroutine.  STARPAC  thus  provides  the 
best  features  of  many  stand-alone  statistical  software  programs 
within  the  flexible  environment  of  a  subroutine  library. 

STARPAC  documentation  is  being  published  as  a  series  of 
Technical  Notes.  This  Note  is  the  first  in  the  series.  It  gives  an 
overview  of  the  STARPAC  library,  defines  conventions  used  in  the 
documentation,  provides  an  example  using  STARPAC  subroutines,  and 
presents  general  background  material.  This  Note  includes 
information  which  is  essential  for  using  the  STARPAC  library,  and 
users  should  be  familiar  with  its  contents  before  attempting  to  use 
any  STARPAC  subroutine. 


Key  words:    data  analysis;   STARPAC;  STARPAC   overview;  statistical 
computing;  statistical  subroutine  library;  STATLIB. 
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CHAPTER  1 
INTRODUCTION  TO  USING  STARPAC 


A.   Overview  of  STARPAC  and  Its  Contents 

STARPAC  is  a  portable  library  of  approximately  150  user-callable  ANSI  '66 
Fortran  subroutines  for  statistical  data  analysis.  Designed  primarily  for 
time  series  analysis  and  for  nonlinear  least  squares  regression,  STARPAC  also 
includes  subroutines  for  normal  random  number  generation,  line  printer  plots, 
basic  statistical  analyses,  linear  least  squares  regression,  and  nonlinear 
optimization.  Emphasis  has  been  placed  on  facilitating  the  interpretation  of 
statistical  analyses,  and,  for  this  reason,  comprehensive  printed  reports  of 
auxiliary  statistical  information,  often  in  graphical  form,  are  automatically 
provided  to  augment  the  basic  statistical  computations  performed  by  each 
user-callable  STARPAC  subroutine.  STARPAC  thus  provides  the  best  features  of 
many  stand-alone  statistical  software  programs  within  the  flexible  environment 
of  a  subroutine  library. 

STARPAC  is  designed  to  be  easy  to  use;  in  many  situations,  only  a  few 
lines  of  elementary  Fortran  code  are  required  for  the  users'  main  programs.  A 
fundamental  STARPAC  philosophy  is  to  provide  two  or  more  user-callable 
subroutines  for  each  method  of  analysis:  one  which  minimizes  the  complexity 
of  the  CALL  statement,  automatically  producing  a  comprehensive  printed  report 
of  the  results;  and  one  or  more  others  which  provide  user  control  of  the 
computations,  allow  suppression  of  all  or  part  of  the  printed  reports,  and/or 
provide  storage  of  computed  results  for  further  analyses. 

STARPAC  has  been  developed  and  is  maintained  by  the  Statistical 
Engineering  Division  of  the  National  Bureau  of  Standards,  Boulder,  Colorado. 
It  is  intended  that  STARPAC  be  a  continually  evolving  library  that  will  keep 
pace  with  new  developments  in  statistical  methods,  and  will  respond  to  the 
ever-changing  needs  of  the  National  Bureau  of  Standards.  Users'  comments  and 
suggestions,  which  have  had  significant  impact  already,  are  highly  valued  and 
always  welcomed.   Comments  and  suggestions  should  be  directed  to: 

Janet  R.  Donaldson 

National  Bureau  of  Standards 

Mail  Code  714 

325  Broadway 

Boulder,  CO  80303. 


B.   Documentation  Conventions 


The  documentation  for  the  various  STARPAC  subroutines  is   being  published 

as   a  series  of  Technical  Notes.    Each  Note  in  the  series  provides  a  standard 

format   description  of  the   information  needed   to  use  a  STARPAC  subroutine, 
including  one  or  more  examples. 


1-1.1 


References  to  chapter  sections  within  the  STARPAC  documentation  are  made 
using  the  symbol  §,  and  refer  to  the  identified  section  within  the  current 
chapter  of  the  current  Note  unless  explicitly  stated  otherwise.  Figures  are 
identified  by  the  section  in  which  they  occur.  For  example,  figure  C-2  refers 
to  the  second  figure  in  §C  of  the  current  chapter  of  this  Note. 

Names  of  INTEGER  and  REAL  STARPAC  subroutine  arguments  are  consistent 
with  the  implicit  Fortran  convention  for  specifying  variable  type.  That  is, 
variable  names  beginning  with  I  through  N  are  type  INTEGER  while  all  others 
are  type  REAL  unless  otherwise  explicitly  typed  DOUBLE  PRECISION  or  COMPLEX. 
All  dimensioned  variables  are  explicitly  declared  in  STARPAC  documentation  by 
means  of  INTEGER,  REAL,  DOUBLE  PRECISION,  or  COMPLEX  statements,  as 
appropriate.  The  convention  used  to  specify  the  dimensioning  statements  is 
discussed  below  in  Sd . 2 . 

The  STARPAC  library  is  available  in  either  single  or  double  precision 
versions,  and  users  should  consult  with  their  computing  center  staff  or 
appropriate  local  documentation  to  determine  which  version  they  are  using. 
The  precision  of  the  STARPAC  library  is  also  indicated  in  the  printed  reports 
generated  by  STARPAC:  an  S  following  the  STARPAC  version  number  in  the  output 
heading  indicates  the  single  precision  version  is  being  used,  while  a  D 
indicates  the  double  precision  version.  The  STARPAC  documentation  is  designed 
for  use  with  both  the  single  and  double  precision  versions.  Subroutine 
arguments  which  are  double  precision  in  both  versions  are  declared  DOUBLE 
PRECISION;  similarly,  arguments  which  are  single  precision  in  both  versions 
are  declared  REAL.  Arguments  whose  precision  is  dependent  upon  the  precision 
of  the  version  of  STARPAC  being  used  are  declared  <real>.  If  the  double 
precision  version  of  the  STARPAC  library  is  being  used,  then  the  user  should 
substitute  DOUBLE  PRECISION  for  <real>;  if  the  single  precision  version  is 
being  used,  then  the  user  should  substitute  REAL  for  <real>.  Other  precision 
dependent  features  are  discussed  as  they  occur. 


C .   A  Sample  Program 

The  sample  program  shown  in  figure  C-l  illustrates  the  use  of  STARPAC 
subroutines.  This  example  was  executed  on  the  CYBER  170/750  at  the  U.S. 
Department  of  Commerce  Boulder  Laboratories  under  the  NOS  1.4  operating  system 
using  a  single  precision  version  of  the  STARPAC  library.  The  code  shown  is 
portable  ANSI  '66  Fortran,  except  for  the  PROGRAM  statement  which  is  required 
by  most  Fortran  compilers  on  CDC  machines.  Section  D  below  uses  this  example 
to  discuss  Fortran  programming  as  it  relates  to  STARPAC. 

The  data  used  in  this  example  are  84  relative  humidity  measurements  taken 
at  Pikes  Peak,  Colorado.  STARPAC  subroutine  PP  plots  the  data  versus 
time-order  (fig.  C-2)  and  STARPAC  subroutine  STAT  prints  a  comprehensive 
statistical  analysis  of  the  data  (fig.  C-3) . 


1-1.2 


MAIN    PR06RANI  PROGRAM    EXAMPL    (INPUT*     OUTPUT.    TAPE5    -    INPUT»    TAPE6    •    OUTPUT) 

C 

REAL    Y(IOO),    X(IOO) 

DOUBLE  PRECISION  DSTAK(IOO) 
C 

COMMON  /CSTAK/  OSTAK 

COMMON  /ERRCHK/  IERR 
C 

C      DEFINE  LDSTAK,  THE  LENGTH  OF  DSTAK 
C 

LDSTAK  -  100 
C 

C      READ  NUMBER  OF  OBSERVATIONS  INTO  N,  AND  DATA  INTO  VECTOR  Y 
C 

READ  (5,  100)  N 

READ  (J,  101)  (Yd),  1-1, N) 
C 

C  CREATE    A    VECTOR    OF    ORDER    INDICES    IN    X 

C 

DO    10    I«1»N 

X(I)    -    FLOAT(I) 
10   CONTINUE 
C 

C  PRINT    TITLE,     PLOT    OF    DATA,    AND    ERROR    INDICATOR 

C 

WRITE    (6,    102) 

CALL    PP    (Y,    X,    N) 

WRITE    (6,    103)    IERR 
C 

C  PRINT    TITLE,     STATISTICAL    ANALYSIS    OF    DATA,    AND    ERROR    INDICATOR 

C 

WRITE    (6,    102) 

CALL  STAT  (Y,  N,  LDSTAK) 

WRITE  (6,  103)  IERR 

STOP 
C 

C      FORMAT  STATEMENTS 
C 

100  FORMAT  (15) 

101  FORMAT  (12F6.*) 

102  FORMAT  (1H1,  48HDAVIS-HARRIS0N  PIKES  PEAK  RELATIVE  HUMIDITY  DATA) 

103  FORMAT  (8H  IERR  >  ,  ID 
END 

DATA l      8* 

.6067  .6087  .6086  .613*  .6106  .6136  .6125  .6122  .6110  .610*  .7213  .7078 

.7021  .700*  .6981  .72*2  .7266  .7*16  .7*07  .7199  .6225  .625*  .6252  .6267 

.6218  .6178  .6216  .6192  .6191  .6250  .6188  .6233  .6225  .620*  .6207  .6168 

.61*1  .6291  .6231  .6222  .6252  .6306  .6376  .6330  .6303  .6301  .6390  .6*23 

.6300  .6260  .6292  .6298  .6290  .6262  .5952  .5951  .631*  .6**0  .6*39  .6326 

.6392  .6*17  .6*12  .6530  .6*11  .6355  .63**  .6623  .6276  .6307  .635*  .6197 

.6153  .63*0  .6336  .628*  .6162  .6252  .63*9  .63**  .6361  .6373  .6337  .6383 


Figure  C-l 
STARPAC  sample  program  and  data 
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D.   Using  STARPAC 

The  following  subsections  provide  general  information  needed  when  using 
STARPAC,  including  a  discussion  of  Fortran  programming  as  it  relates  to 
STARPAC  usage.  Although  only  elementary  knowledge  of  Fortran  is  required  to 
use  STARPAC,  users  may  still  have  to  consult  with  a  Fortran  test  and/or  their 
computing  center  staff  when  questions  arise. 


D.l   The  PROGRAM  Statement 

The  PROGRAM  statement,  which  is  required  by  most  Fortran  compilers  on  CDC 

machines,  serves  two  purposes:    the  first  is  to  name  the  user's  main  program; 

and  the   second  is   to  specify   the   files  (devices)  which  will   be  used  for 

reading  and  writing  information  during   execution  of  the  user's  program.    In 
figure  C-l,  the  PROGRAM  statement  is 

PROGRAM  EXAMPL  (INPUT,  OUTPUT,  TAPE5  =  INPUT,  TAPE6  =  OUTPUT). 

The  name  EXAMPL  is  assigned  to  the  main  program  in  this  example.  The 
program  name  cannot  be  the  name  of  any  variable  in  the  user's  main  program 
and,  in  addition,  cannot  be  the  name  of  any  other  subroutine  or  function 
called  during  execution  of  the  user's  code.  Specifically,  it  cannot  be  the 
name  of  any  subroutine  within  STARPAC.  To  ensure  that  the  name  of  a  STARPAC 
subroutine  is  not  inadvertently  chosen  for  the  name  of  the  main  program,  users 
should  consult  with  the  local  installer  of  STARPAC  to  obtain  a  list  of  the 
STARPAC  subroutine  names. 

The  file  declaration  function  of  the  program  statement  is  machine 
dependent.  The  files  declared  in  the  program  statements  used  in  this  example 
and  throughout  the  STARPAC  documentation  are  those  required  when  using  STARPAC 
on  the  CYBER  170/7  50  at  the  U.S.  Department  of  Commerce  Boulder  Laboratories 
under  the  NOS  1.4  operating  systems.  Users  at  other  installations  should 
consult  §D.4  and  the  local  installer  of  STARPAC  for  additional  information  on 
controlling  file  specification. 


D.2   The  Dimensioning  Statements 

The  user's  program  must  include   dimensioning  statements  to   define  the 

sizes   and   types    of   the   vectors   (1-dimensional   arrays)  and  matrices 

(2-dimensional   arrays)   required  by   each  STARPAC   subroutine  used;   STARPAC 
itself  has  no  inherent  upper  limit  problem  size. 

Within  the  STARPAC  documentation  for  the  subroutine  declaration  and  CALL 
statements,  italicized  lowercase  identifiers  in  the  dimensioning  statements 
represent  integer  constants  which  must  equal  or  exceed  the  value  of  the 
identically  spelled  uppercase  argument.  For  example,  if  the  documentation 
specifies  the  minimum  dimension  of  a  variable  as  <real>  XM(?z,w),  and  if  the 
number  of  observations  N  is  15,  and  the  number  of  columns  of  data  M  is  3,  then 
(assuming  the  single  precision  version  of  STARPAC  is  being  used)  the  minimum 
array  size  is  given  by  the  dimensioning  statement  REAL  XM(15,3). 
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The  exact  dimensions  assigned  to  some  vectors  and  matrices  must  be 
supplied  in  the  CALL  statements  to  some  STARPAC  subroutines.  For  example,  the 
argument  1XM  is  defined  as  "the  exact  value  of  the  first  dimension  of  the 
matrix  XM  as  declared  in  the  calling  program."  Continuing  the  example  from 
the  preceding  paragraph,  if  the  statement  REAL  XM(20,5)  is  used  to  dimension 
the  matrix  XM  for  a  particular  subroutine,  and  IXM  is  an  argument  in  the  CALL 
statement,  then  IXM  must  have  the  value  20  regardless  of  the  value  assigned  to 
the  variable  N. 

Many  STARPAC  subroutines  require  a  work  area  for  internal  computations. 
This  work  area  is  provided  by  the  DOUBLE  PRECISION  vector  DSTAK.  The  rules 
for  defining  DSTAK  are  as  follows. 

1.  Programs  which  call  subroutines  requiring  the  work  vector  DSTAK  must 
include  both  the   statement 

COMMON  /CSTAK/  DSTAK 

and  the  DOUBLE  PRECISION  statement  dimensioning  DSTAK. 

2.  Since  all  STARPAC  subroutines  use  the  same  work  vector,  the  length  of 
DSTAK  must  equal  or  exceed  the  longest  length  required  by  any  of  the 
individual  STARPAC  subroutines  called  by  the  user' s  program. 

3.  The  length,  LDSTAK,  of  the  work  vector  DSTAK  must  be  specified  in  the 
CALL  statement  of  any  STARPAC  subroutine  using  DSTAK  to  enable  STARPAC 
to  verify  that  there  will  be  sufficient  work  area  for  the  problem. 

It  is  recommended  that  a  variable  LDSTAK  be  set  to  the  length  of  DSTAK, 
and  that  this  variable  be  used  in  each  CALL  statement  requiring  the  length  of 
DSTAK  to  be  specified.  Then,  if  a  future  modification  to  the  user's  program 
requires  the  length  of  DSTAK  to  be  changed,  the  only  alterations  required  in 
the  existing  code  would  be  to  the  DOUBLE  PRECISION  dimensioning  statement  and 
to  the  statement  which  assigns  the  length  of  DSTAK  to  LDSTAK. 

STARPAC  manages  its  work  area  using  subroutines  modeled  after  those  in 
ACM  Algorithm  528:  Framework  for  a  Portable  Library  [Fox  et  al. ,  1978a] . 
Although  STARPAC  and  the  Framework  share  the  same  COMMON  for  their  work  areas, 
there  are  differences  between  the  STARPAC  management  subroutines  and  those  of 
the  Framework.  In  particular,  the  STARPAC  management  subroutines 
re-initialize  DSTAK  each  time  the  user  invokes  a  STARPAC  subroutine  requiring 
work  area,  destroying  all  data  previously  stored  in  DSTAK;  the  Framework  only 
initializes  DSTAK  the  first  time  any  of  its  management  subroutines  are 
invoked,  preserving  work  area  allocations  still  in  use.  Thus,  users  must  be 
cautious  when  utilizing  STARPAC  with  other  libraries  which  employ  the 
Framework,  such  as  PORT  [Fox  et  al. ,  1978b]. 

The  sample  program  shown  in  figure  D-l  provides  an  example  of  the  use  of 
dimensioned  variables  with  STARPAC.  The  REAL  vector  Y,  used  by  both 
subroutines  PP  and  STAT,  contains  the  84  relative  humidity  measurements;  its 
minimum  length,  N  (the  number  of  observations) ,  is  84.  The  REAL  vector  X  used 
by  subroutine  PP  contains  the   corresponding  time   order  indices  of   the  data; 


1-1.7 


its  minimum  length  is  also  84.  The  DOUBLE  PRECISION  vector  DSTAK  contains  the 
work  area  needed  by  STAT  for  intermediate  computations;  its  minimum  length  is 
49  in  this  case.  In  this  example,  the  dimensions  of  Y,  X,  and  DSTAK,  are  each 
100,  exceeding  the  required  minimum  values. 


D.3   The  CALL  Statements 

The  STARPAC  CALL  statement  arguments  provide  the  interface  for  specifying 
the  data  to  be  used,  controlling  the  computations,  and  providing  space  for  any 
returned  results.  The  CALL  statements  used  in  the  example  are 
CALL  PP(Y,  X,  N)  and  CALL  STAT(Y,  N,  LDSTAK) .  Note  that  scalar  arguments  may 
be  specified  either  by  a  variable  preset  to  the  desired  value,  as  was  done  in 
figure  C-l,  or  by  the  actual  numerical  values.  For  example,  CALL  PP(Y,  X,  84) 
and  CALL  STAT(Y,  84,  100)  could  have  been  used  instead  of  the  forms  shown.  We 
recommend  using  variables  rather  than  the  actual  numerical  values  in  order  to 
simplify  future  changes  in  the  program.  When  variables  are  used,  changes  need 
to  be  made  in  only  one  place;  numerical  values  have  to  be  changed  every  place 
they  occur.  In  addition,  the  use  of  variables  can  also  clarify  the  meaning  of 
the  program. 


D . 4   STARPAC  Output 

Most  STARPAC  subroutines  produce  extensive  printed  reports,  freeing  the 
user  from  formatting  and  printing  each  statistic  of  interest.  The  standard 
output  device  is  used  for  these  reports.  The  user  has  the  options  of  titling 
the  reports  and  changing  the  output  device. 

The  first  page  of  the  report  from  each  STARPAC  subroutine  does  not  start 
on  a  new  page.   This  allows  the  user  to  supply  titles.   For  example, 

WRITE  (6,  100) 
100  FORMAT  (1H1,  4 8H DAVIS-HARRISON  PIKES  PEAK  RELATIVE  HUMIDITY  DATA) 
CALL  PP  (Y,  X,  N) 

will  print  the  title  DAVIS-HARRISON  PIKES  PEAK  RELATIVE  HUMIDITY  DATA  on  the 
top  line  of  a  new  page,  immediately  preceding  the  plot  as  shown  in  figure  C-2. 
Users  should  note  that  titles  more  than  one  line  in  length  can  cause  a  printed 
report  designed  for  one  page  to  extend  beyond  the  bottom  of  the  page. 

The  unit  number,  IPRT,  of  the  output  device  used  by  STARPAC  is  returned 
by  STARPAC  subroutine  IPRINT.  Users  can  change  the  output  device  unit  number 
by  including  with  their  program  a  subroutine  IPRINT  which  will  supersede  the 
STARPAC  subroutine  of  the  same  name.   The  subroutine  must  have  the  form 

SUBROUTINE  IPRINT(IPRT) 

IPRT  =  u 

RETURN 

END 

where  u  is  an  integer  value  specifying  the  output  unit  to  which  all  STARPAC 
output  will  be  written. 
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D.5   STARPAC  Error  Handling 

STARPAC  provides  extensive  error-checking  facilities  which  include  both 
printed  reports  and  a  program-accessible  error  flag  variable.  There  are 
essentially  two  types  of  errors  STARPAC  can  detect. 

The  first  type  of  error  involves  incorrect  problem  specification,  i.e., 
one  or  more  of  the  input  arguments  in  the  subroutine  statement  has  an  improper 
value.  For  example,  the  number  of  observations,  N,  might  have  an  obviously 
meaningless  non-positive  value.  In  the  case  of  improper  problem  specification 
STARPAC  generates  a  printed  report  identifying  the  subroutine  involved,  the 
error  detected,  and  the  proper  form  of  the  subroutine  CALL  statement.  The 
latter  is  provided  because  improper  input  is  often  the  result  of  an 
incorrectly  specified  subroutine  argument  list. 

A  second  type  of  error  can  be  thought  of  as  a  computation  error:  either 
the  results  from  the  called  subroutine  are  questionable,  or  the  initiated 
calculation  cannot  be  completed.  For  example,  when  one  or  more  of  the 
standardized  residuals  from  a  least  squares  fit  cannot  be  computed  because  the 
standard  deviation  of  the  residual  is  zero,  the  results  of  the  error  estimates 
from  the  least  squares  regression  may  be  questionable;  if  the  least  squares 
model  is  found  to  be  singular,  then  the  desired  computations  cannot  be 
completed.  In  the  case  of  a  computation  error,  STARPAC  generates  a  report 
which  identifies  the  computation  error,  and,  to  aid  the  user  in  determining 
the  cause  of  the  error,  summarizes  the  completed  results  in  a  printed  report. 

STARPAC  error  reports  cannot  be  suppressed,  even  when  the  normal  output 
from  the  STARPAC  subroutine  has  been  suppressed.  Because  of  this,  users 
seldom  have  to  consciously   consider  handling  error  conditions  in   their  code. 

When  proper  execution  of  the  user' s  program  depends  on  knowing  whether  or 
not  an  error  has  been  detected,  the  error  flag  can  be  examined  from  within  the 
user's  code.   When  access  to  the  error  flag  is  desired,  the  statement 

COMMON  /ERRCHK/  IERR 

must  be  placed  with  the  Fortran  declaration  statements  in  the  user's  program. 
Following  the  execution  of  a  STARPAC  subroutine,  the  variable  IERR  will  be  set 
to  zero  if  no  errors  were  detected,  and  to  a  nonzero  value  otherwise;  the 
value  of  IERR  may  indicate  the  type  of  error  [e.g.,  see  Donaldson  and  Tryon, 
1983,  chapter  1,  §D,  argument  IERR].  If  the  CALL  statement  is  followed  with  a 
statement  of  the  form 

IF  (IERR  .NE.  0)  STOP 

then  the  program  will  stop  when  an  error  is  detected.  (In  figure  C-l ,  the 
value  of  IERR  has  been  printed  following  each  CALL  statement  to  show  the  value 
returned. ) 


'STARPAC  output  must  be  directed  to   a  separate  output  device  [see   §D.4]  when 
users  do  not  want  any  STARPAC  reports  displayed  under  any  conditions. 
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D. 6   Common  Programming  Errors  When  Using  STARPAC 

STARPAC  error  checking  procedures  catch  many  programming  errors  and  print 
informative  diagnostics  when  such  errors  are  detected.  However,  there  are 
some  errors  which  STARPAC  cannot  detect.  The  more  common  of  these  are 
discussed  below. 

1.  The  most  common  error  involves  array  dimensions  which  are  too  small. 
Although  certain  arguments  are  checked  by  STARPAC  to  verify  that  array 
dimensions  are  adequate,  if  incorrect  information  is  supplied  to 
STARPAC,  or  if  the  dimension  of  an  array  which  is  not  checked  is  too 
small,  the  program  will  produce  erroneous  results  and/or  will  stop 
prematurely.  Users  should  check  the  dimensioning  statements  in  their 
program  whenever  difficulties  are  encountered  in  using  STARPAC. 

2.  The  second  most  common  error  involves  incorrect  CALL  statements,  that 
is,  CALL  statements  in  which  the  STARPAC  subroutine  name  is 
misspelled,  the  arguments  are  incorrectly  ordered,  one  or  more 
arguments  are  omitted,  or  the  argument  types  (INTEGER,  REAL,  DOUBLE 
PRECISION,  and  COMPLEX)  are  incorrect.  Users  having  problems  using 
STARPAC  should  carefully  check  their  declaration  and  CALL  statements 
to  verify  that  they  agree  with  the  documentation. 

3.  The  third  most  common  error  involves  incorrect  specification  of  the 
work  vector  DSTAK.  Programs  which  call  STARPAC  subroutines  requiring 
work  area  must  include  both  the  DOUBLE  PRECISION  statement 
dimensioning  DSTAK  and  the  COMMON  /CSTAK/  DSTAK  statement. 

4.  The  final  common  error  involves  user-supplied  subroutines  which  have 
the  same  name  as  a  subroutine  in  the  STARPAC  library.  Users  should 
consult  with  the  local  installer  of  STARPAC  to  obtain  a  list  of  all 
STARPAC  subroutine  names.  This  list  can  then  be  used  to  ensure  that  a 
STARPAC  subroutine  name  has  not  been  duplicated. 

Users  who  have  not  found  the  cause  of  a  problem  after  checking  the 
possibilities  mentioned  above  should  consult  with  their  computing  center 
advisers. 
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